Allow users to specify a custom refspec for fetching in lightweight
checkout mode via GitSCMFileSystem. This enables SCMFileSystem to
fetch specific revisions rather than always fetching the branch tip.

Add support for:
- Custom refspec from UserRemoteConfig.getRefspec()
- FETCH_HEAD as a valid branch specification
- Raw commit hashes as branch specification
- refs/changes/* prefix for Gerrit change refs

These changes enable lightweight checkout to be used for:
- Gerrit changes using refs/changes/* refspecs with FETCH_HEAD
- Checking out a specific commit instead of branch HEAD

Centralize branch name resolution, prefix detection, commit hash
matching, and refspec construction inside HeadNameResult.calculate().
Previously this logic was split between the BuilderImpl.build() method
and HeadNameResult, making the flow hard to follow.

- Add remoteName parameter for constructing remote-tracking refs
- Add remoteHeadName, refspec, and rev fields to HeadNameResult
- Move FETCH_HEAD detection from build() into calculate()
- Move commit hash matching from build() into calculate()
- Move refspec construction from build() into calculate()
- Simplify build() to delegate entirely to HeadNameResult.calculate()
- Add unit tests for head name calculation with refspecs, commits,
  and FETCH_HEAD

Replace reference equality (==) with value equality (.equals()) when
comparing the prefix against Constants.R_HEADS and Constants.R_TAGS.
The == operator may fail for string values that are equal but not
the same object instance.

The prefix variable can be null when the branch specification is
FETCH_HEAD or a raw commit hash. Add a null check before calling
.equals() to prevent a NullPointerException.

Replace the hardcoded "FETCH_HEAD" string literal with the JGit
constant Constants.FETCH_HEAD in both production code and tests.
This improves maintainability and ensures consistency if the
constant value ever changes.

Extract a getFileContent() helper method to reduce duplication
in the file tree traversal assertions across multiple test methods.
Move createRepoListWithRefspec() helper adjacent to it.

Add new test methods:
- create_SCMFileSystem_from_commit: verify checkout at a specific
  commit revision
- create_SCMFileSystem_from_FETCH_HEAD: verify checkout using a
  custom refspec with FETCH_HEAD

Add static import for GitSCMFileSystem.BuilderImpl.HeadNameResult
and use the short name throughout calculate_head_name_with_env().
This reduces line length and improves readability of the test
assertions.

The headName field in HeadNameResult is reported as unread by
spotbugs (URF_UNREAD_FIELD). Suppress this warning temporarily
while investigating the proper resolution.

Note: This exclusion is removed in a subsequent commit once the
field is properly used in logging output.

Rename the local variable headName to calculatedHeadName inside
HeadNameResult.calculate() to avoid confusion with the
HeadNameResult.headName field. This makes the code easier to
understand by distinguishing the temporary local value from the
result object's field of the same name.

Include the remote name and resolved head name in the "Done." log
message so users can see which branch or commit was actually used
during the fetch operation.

Also remove the spotbugs URF_UNREAD_FIELD exclusion for
HeadNameResult.headName, which is now properly accessed through
the logging statement.

Update the refSpec parameter annotation in HeadNameResult.calculate()
from @nonnull to @checkfornull. The existing tests pass null for this
parameter, and the implementation already handles null correctly by
constructing a default refspec when none is provided.

Extend the static import of HeadNameResult to cover
calculate_head_name(), calculate_head_name_with_refspec_commit(),
calculate_head_name_with_refspec_FETCH_HEAD(), and
calculate_revision_head_name() test methods. This completes the
cleanup started in an earlier commit.

Fix the refspec calculation for tag branches. Previously a lightweight
checkout of a tag would generate a refspec mapping the tag to
refs/remotes/origin/<tag>, which places the tag reference in the
wrong namespace.

Now tag refspecs use +refs/tags/<name>:refs/tags/<name>, keeping tag
references in the correct refs/tags/ namespace. The remoteHeadName
for tags is also corrected to use just the tag name instead of the
remote-tracking path.

Additionally add a null guard when expanding refspec environment
variables to prevent NPE when refspecExpandedName is null.

The headName field in HeadNameResult was only used internally for
constructing the remoteHeadName. Since remoteHeadName is now always
a fully qualified reference (either refs/remotes/<remote>/<name>
for branches or the raw name for tags/commits/FETCH_HEAD), the
separate headName field is no longer needed.

- Remove headName from HeadNameResult constructor and fields
- Update callers to use remoteHeadName instead of headName
- Update test assertions to verify remoteHeadName directly